Linux Cubed Series 7: Sunsite/Linux Cubed Series 7 - Sunsite Vol 1.iso/system/emulator/uae-0.000/uae-0/uae-0.6.0/README

Text File | 1996-06-14 | 26KB | 524 lines

This is version 0.6.0 of UAE, the Un*x Amiga Emulator.

1. <drivel.h>

Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is
freeware.  You may do whatever you want with it for personal use.
Permission is granted to redistribute this program free of charge, provided it
is distributed in the full archive with unmodified contents. No profit beyond
the price of the media on which it is distributed is made. Exception to the
last rule: It may be included on freeware/shareware collections on CD-ROM.
There are no warranties of any kind for this program. If you use this program,
you do so at your own risk. The authors are not responsible for any damages
that might result from using this program.

2. Overview

UAE emulates the hardware of an A500 with 2MB chip and a variable amount of
fast memory. Up to 11.8MB RAM are supported. It works with all Kickstart ROM
versions, provided they are not compiled for the 68020. It supports some (one,
to be precise) ECS features apart from nearly all the functionality of an OCS
chipset.

UAE was developed for Unixoid systems. Meanwhile, it has been ported to the
Mac, DOS, the BeBox, NextStep and AA Amigas (it can't quite run itself yet).
The Mac and DOS versions are distributed with binaries and a seperate README
file that you should read after you have finished this document. The other
versions must be compiled from the source code.

What UAE does not (yet) emulate is software. To use UAE, you need a Kickstart
ROM image as well as any other software you want to run, e.g. a Workbench
disk. Both are copyrighted, and I can't include them. Don't ask me to send
them to you.
Since the PC floppy controller can't read Amiga disks (yes, that's a fact),
floppy access has to be emulated differently: Floppies are emulated by means
of disk files that contain a raw image of the floppy disk you want to emulate.
Read the section "tools" below for information how to create ROM images and
disk files.
You can also emulate a harddisk. UAE can mount native filesystems as
harddrives, so once you have booted it up, you can access all your files on
the harddisk. It is currently impossible to boot from the emulated harddisk.
I don't have a clue why.

I am developing UAE using Linux. Only if you are running Linux can you be
reasonably sure that all versions of UAE will work for you. On other Unix
systems, you may encounter problems from time to time. I can make no
guarantees about the NextStep and BeBox versions, these are very recent ports
and will probably need some more time before they compile/run reliably.

These are the requirements for getting the Unix version to run:
  - X11, or SVGAlib if you are using Linux.
  - an ANSI C compiler. GCC is _strongly_ recommended.
  - Optionally, tcl7.4/tk4.0

Note: some Linux installations (usually Slackware) are broken. If you get
linker errors ("final link failed: bad value"), you need to upgrade the
binutils package that you can find on sunsite.unc.edu:/pub/Linux/GCC
Before installing anything from that directory, read the corresponding
release.* files.
You'll get better performance if you are using an ELF system.

On Linux, 8MB are sufficient to run UAE, although startup will be much faster
if you have some additional memory. The DOS version also works with 8MB, but
startup is slow there too. I have not tried the other ports, it may well be
that other OS's are better at wasting memory. At least 16MB are recommended.

This section is just what it says: an overview. Please read _all_ of this
file, especially if you have problems. Please read also the file "FAQ" which
contains some Frequently Asked Questions (and even the answers!)

3. Installation

To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
on a Linux system). After that, you will have to edit the file config.h to set
some configuration options. Then, you should give the command "configure".
This script will determine what type of system you are using. It will then
create an appropriate Makefile. Type "make" if configure exited successfully
to build UAE.
If you are running Linux, you can say "configure --without-x" as an
alternative. If you do this, UAE will be configured to use the SVGA library.
If you use SVGAlib, be warned that SVGAlib is not too stable and using it is
inherently a little dangerous, you might want to have a way to log in from a
remote terminal if things go horribly wrong. If you are very unfortunate, you
might lock up your machine otherwise.
If you have a BeBox, you should not run configure. Instead, compile UAE by
doing "make -f Makefile.Be".

If you configure UAE for building the X11 version (which is the default if you
simply say "configure"), the configure script will try to find the program
"wish4.0" in the path. This program is installed if you have Tk 4.0. If it is
found, the X11 version will use a graphical user interface that enables you to
switch diskfiles.

The compilation may take a while, especially for the cpu*.c files. There might
be some warnings, ignore these. It may also take a lot of memory. You should
have at least 8MB physical RAM to compile this, plus maybe 10MB swap and 9MB
filesystem space.

After compilation, you'll need to install the ROM image. This must have a size
of exactly 512K (if you only have a 256K image of a 1.x Kickstart, that should
work, too) and should be an image of the addresses 0xF80000-0xFFFFFF on
your Amiga system. The file must be called kick.rom to be recognized. Please
read the next section on how to transfer files from your Amiga to your PC.

You also need to install a disk image file. This must be called df0.adf (adf =
Amiga Disk File), and should be a raw image of the data on the floppy disk:
11x2x80 sectors == 901120 bytes.
Please try running UAE without a diskfile first. If everything went O.K., the
emulator should show the Kickstart logo (don't be too impatient, this will
take a while on slow machines).

If you don't have a Kickstart file, you may still be able to boot some games
and demos. The emulator includes some primitive bootstrap code that will try
to read and execute the bootblock of the diskfile you are using, and if that
bootblock only uses the one or two Kickstart functions that are supported by
the "replacement Kickstart", your program will boot. Don't expect too much,
though.

4. Invoking UAE

After building the program, you should have an executable called "uae". You
can simply execute it, but you can also optionally give it one of the following
parameters:

 -h      : Give help on the options.
 -f rate : Sets the frame rate
 -D      : Don't start the emulator at once, use the built-in debugger.
 -a      : Don't mount the harddisk file automatically. (Useful only for
           testing purposes)
 -l lang : Set the keyboard language at run-time. Currently, the following
           values can be used for lang: "us" for U.S. keyboard (default), "se"
       for swedish, "fr" for french, "it" for italian  or "de" for german
       keyboard.
 -s      : Emulate slow memory at 0xC00000. Some demos/games need this.
 -F n    : Emulate n megabytes of fast memory as an expansion board.
 -S      : If you set the LINUX_SOUND option in config.h, you can turn off
           sound output with this switch.
 -M VOLUME:path
 -m VOLUME:path
           mount the unix file system at path as an Amiga filesystem with
       volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules"
       If you use -M instead of -m, the volume will be read only.
       See below.
 -0 file : Try to use file as diskfile for drive 0 instead of df0.adf.
           -1 file, -2 file and -3 also exist for the other drives.
 -r file : Use file instead of kick.rom as Kickstart image.
 -J      : Use the numeric pad for joystick emulation (with 5 as fire button).
           This will turn off real joystick support. It's no good for action
       games, but may be useful for other games.
 -d mode : Select a graphical resolution for UAE to run in.
 -H      : Select a color mode to use.
 -p cmd  : Enable printing. See below.
 -x      : General-purpose option. For the X version, it makes the X cursor
           visible (recommended). For the SVGAlib version, it turns off
       linear framebuffer support (sometimes, with -d 4, SVGAlib is
       faster without linear framebuffer).

Resolutions: 0 (320x200); 1 (320x240); 2 (320x400); 3 (800x600, default);
             4 (800x600 with correct aspect).
Color modes: 0 (256 colors, default); 1 (32768 colors); 2 (65536 colors)
UAE may choose to ignore and/or refuse some combinations of these two
parameters. The low-resolution modes are mostly meant for SVGAlib and the DOS
version. Some of these modes may also fail to work on your system.

The low-resolution (320x???) modes should help some of the proud owners of new
P6 systems with a broken chipset and an exciting PCI performance of 4MB/s :-)
But if SVGAlib supports linear mode for your graphics card, 800x600 might in
fact be faster than 320x200 (it's like this on my system). Experiment a
little.

You can also put these options into a configuration file in your home
directory. Simply create ~/.uaerc and put some of these options in it. On
non-Unix systems, the file is called uae.rc and should be located in the
current directory.

If you use SVGAlib, the only way to leave the program is pressing F12.

5. Harddisk emulation

Using diskfiles is awkward. There are two ways how you can use larger amounts
of data with UAE.

a) Harddisk files.
You can create a harddisk file with

  dd if=/dev/zero of=hardfile bs=512 count=16384

Currently, the size is fixed (8MB). Note that this method does not work with
Kickstart versions <=1.3 for some reason.

The harddisk file is accessed by a resident ROM module that is built into the
emulator. It's called "uae.device", the DOS name for the harddisk is "uae0:".
You have to format it before use (from AmigaDOS).

I don't think I will support this in the future. If I get no emails from users
protesting "I put all my files on it" (I got some already, so it's going to
stay a while), I'll remove the code again, because you can

b) Access native filesystems from the emulator.

This has some major advantages:
 - It also works with Kickstart 1.3.
 - It is more convenient.
 - It is much faster. In fact, it can be dramatically faster even than a real
   Amiga when reading directories.

However, it currently does not work on some ports.

If you specify the -M or -m command line arguments, you can use files on your
Unix filesystem from the emulator. If you start UAE with

  uae -m sound:/usr/amiga/modules

you can access all the files in /usr/amiga/modules by reading from the
AmigaDOS volume "SOUND:".
If you want to execute files, they need to have the x permission bit set.
That can be done in Unix by "chmod +x file" or in AmigaDOS with
"protect file rwed".
In theory, you can specify this option multiple times. In practice, this
doesn't work with Kickstart 1.3, but will probably work with newer Kickstarts.

6. Tools / Transferring files

In the "amiga" subdirectory you'll find two small tools that you can use to
transfer software from the Amiga to the PC. These are called transrom and
transdisk. transrom will dump the contents of your Kickstart ROM, and
transdisk will dump an image of the floppy in drive DF0:. Both programs write
to the standard output, so you want to redirect that. Do

   transrom >ram:kick.rom

to create a file called "kick.rom" in the RAM disk, and

   transdisk >ram:df0.adf

to create a file called "df0.adf" in the RAM disk. These files are pretty
big, 524288 bytes for the ROM image and 901120 bytes for a disk image. If you
are short on RAM (less than 1.5MB) you may want to transfer those files
directly to a serial link between the Amiga and your Un*x system (works
without a problem for me).
transdisk understands the following arguments:

    -d device unit: Use this device instead of DF0:
    -s n: Begin transfer at track n (default: 0)
    -e n: End transfer at track n (default: 79)

So, to transfer the disk in drive DF1:, you'd give the command:

  transdisk >ram:df1.adf -d trackdisk 1

If you are low on disk space, you can split up the transfer into multiple
parts with the "-s" and "-e" parameters. To transfer the disk in four parts,
you'd use the following commands:

  transdisk >ram:df0_1.adf -s 0 -e 19
  transdisk >ram:df0_2.adf -s 20 -e 39
  transdisk >ram:df0_3.adf -s 40 -e 59
  transdisk >ram:df0_4.adf -s 60 -e 79

Of course, you should save each of the four files from the RAM disk to
another place before transferring the next one with transdisk to make space
in your RAM disk. If you have all the files on your PC, you can do the
following under Unix:
  cat df0_1.adf df0_2.adf df0_3.adf df0_4.adf >df0.adf
or, under DOS:
  COPY /B df0_1.adf df0_2.adf df0_3.adf df0_4.adf df0.adf
I don't know how to do that with other operating systems (Mac...).

The current transdisk can only read the standard AmigaDOS format. You will
not be able to transfer copy protected disks. Although the current emulator
version can handle a second type of disk file, and I have successfully
transferred and run a copy protected game (Turrican I) on the emulator, this
support is preliminary, and the disk file format for non-standard disk formats
will probably change in future versions. If you also have Turrican and want
the program I used to transfer the disk, mail me.

If you have connected your Amiga to your Linux box with a serial cable, you
can do

  transdisk >SER: <options>

on the Amiga to copy the data directly to the serial port. Before that, do

  cat /dev/ttyS1 >df0.adf

on your Linux box to receive the data (it may be ttyS0 on your system, or
another number, depending on which serial port you are using). When the Amiga
is done transferring, hit ^C on the PC to interrupt the cat program. To make
this work, you need to use the same settings for the serial port on both
sides. This is done with the Preferences program on the Amiga (this is split
into several programs from Kickstart 2.0 upwards, you'll find a program called
"serial" in the Prefs directory of your Workbench disk). On the Linux side,
use the stty program. "man stty" will give you the manpage describing how to
use it.
To be on the safe side, set the speed to a low value (2400 baud). Turn off
Xon/Xoff, but enable RTS/CTS.
I use the following command myself:

  stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost
    -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1

which is probably overkill, but you never know :)
This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to
set in the Amiga preferences.
I have no idea how to use a serial cable with DOS. I tried the obvious way
"COPY SER: file" one day, and it did not seem to work. I'm sorry, but I can't
help here.

If you don't have a serial cable, you need to use a tool like CrossDOS,
which is bundled with newer versions of the Amiga OS, or messydisk, which is
PD and can be found on an old Fish disk. These will allow you to write MS-DOG
formatted disks on the Amiga.

If you transfer commercial software, you must not distribute the resulting
image files, since that would be a violation of copyright law. The Kickstart
ROM has to be considered commercial software. You may only use the Kickstart
from your own Amiga, and you may not distribute Kickstart ROM files.
Please read the license that came with your software for details.

If you have a disk image file, and you want to retrieve the files from it, you
can use the "readdisk" tool. It is automatically built by "make". If you have
a disk image of a disk called "Workbench1.3D" as df0.adf, and you do
   readdisk df0.adf
the whole directory structure of the disk image will be stored in a newly
created subdirectory called "Workbench1.3D". You can optionally give a second
parameter to specify a directory where to create the output other than the
current directory.
readdisk only understands about the OFS right now. FFS disks will cheerfully
be regarded as being unreadable. Use the unixfs.device from within the
emulator if you want to transfer files from FFS disks.

7. Printing

With the "-p cmd" option, you can specify a command that will be run when the
emulator detects that the Amiga accesses the parallel port. Usually, you will
want to say "-p lpr" to pass the output over to lpd. It's unclear how this
will work on non-Unix systems, DOS users can try "-p LPT1:" or something like
this.
For best results, select the PostScript driver in the Amiga Preferences. This
is only available in newer Kickstarts. Printing is not going to work with
another printer driver.
None of this is guaranteed to work yet, and I have not tried any of this yet.

8. Quick overview of the debugger commands

If you use the X Windows version, you can press ^C at any time to enter the
built-in MC68000 debugger.
Each debugger command consists of a single letter and occasionally some
parameters.

g:                    Start execution at the current address.
c:                    Dump state of the CIA and custom chips.
r:                    Dump state of the CPU
m <address> <lines>:  Memory dump starting at <address>
d <address> <lines>:  Disassembly starting at <address>
t:                    Step one instruction
z:                    Step through one instruction - useful for JSR, DBRA etc.
f <address>:          Step forward until PC == <address>
q:                    Quit the emulator. You don't want to use this command.

(^C has no effect if UAE is compiled for SVGAlib - use F12 to exit)

9. Input devices

Mouse, keyboard and joystick can be used in a straightforward way. A couple of
keyboard languages are supported with the "-l" commandline option. If you have
a different keyboard, patches to make UAE work with it are appreciated.
The X version of the emulator will try to keep the Amiga mouse pointer at the
same location as the X mouse pointer. You can turn off this mode if it does
not work with your program by pressing F12. This is needed (for example) for
Lemmings and the Magnetic Scrolls adventures, which don't use sprite 0 as a
mouse pointer. Other versions (SVGAlib, DOS, possibly others) do not have this
problem.
If you use Linux and have the joystick driver kernel module, "configure"
should automatically enable support for it. UAE calibrates the joystick
automatically. Turn it a few times on startup to get the calibration done.

10. Sound

If you define LINUX_SOUND in config.h, the emulator will use /dev/dsp to
output sound. It will try to set the output to 16bit/44100 Hz, but will fall
back to 8bit/22050Hz if the sound card does not support this (I hope so, at
least. Can anyone try this?). If graphics output is enabled while sound is
output, the emulator will be much too slow on all current systems. The
sound will not be continuous. Therefore, a hack to turn off screen updates is
provided: Press ScrollLock to disable graphics, press it again to enable them
(note: for X, you'll have to press it twice each time).
The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator.
The relative CPU speed will be reduced somewhat if this option is set. This may
lead to incompatibilities. The system should not be heavily loaded (no blitter
or disk activity) while sound is being played, or even this will be too slow.
Only a subset of the Amiga sound hardware is emulated. Attached channels are
not implemented, neither is CPU-driven output.

Currently, this implementation is good enough to play *Tracker modules and
some game title melodies. It is fast enough (on a P90, without the
LINUX_SOUND_SLOW_MACHINE option) to play modules using a Workbench player
program if no other (Amiga) processes are active.

On other Unix systems, the AF sound system may be available. You can configure
UAE to use this, too, by changing some paths in the Makefile (I can't answer
any questions about this, I never saw/used it).

11. Speed

The Most Frequently Asked Question is: "Just how fast is it?", and this is
also the most difficult one to answer. The easy way to answer is "It depends",
but I'll try to do better. All timings I give here were measured on my
machine, a P90 (using SVGAlib, with all the x86 assembly options turned on).
The MC68000 emulation is more than twice as fast as a real A500. I measured
this by letting PowerPacker try to compress itself (it already was compressed).
It took UAE about 6 minutes, my A500 took about 15. If you set the frame rate
to a high value (i.e. leaving out many frames), the graphics speed does not
matter and you get about twice the speed of an A500. If you enable the smart
update method in config.h, and if it works for your program (it works for
almost all programs using the Workbench) you also get about the same speed at
full frame rate.
For games and demos, the CPU speed does not matter, but the average frame time
is important. UAE can calculate this automatically. The SVGAlib version gives
the number when you exit the emulator, to obtain the value with the X version
you need to interrupt it and type "c" in the debugger. A real A500 has a
constant frame time of 20ms (50 Hz).
If you have a game/demo that has lots of blitter activity, many copper/sprite
effects, dual playfields and scrolling, no one can help you. Fortunately, this
case is extremely rare. Normal games that have a number of blitter objects,
scrolling and maybe some sprites run at 1/3-1/4 the speed of an A500 in the
worst case, some run at 1/2 the speed. Lowering the frame rate helps
enormously here, and at 1/5 frame rate, about everything runs somewhere
between 50% and 100% the speed of an A500.
This still isn't the full story (I bet you start to see why the question is
hard to answer). A real A500 without fast memory gets slowed down to about
half its speed in Hires 16 color mode. More bitplanes also slow UAE down, but
not quite as much, so it can be several times faster than an A500 in that
mode.

12. Bugs / Unimplemented features.

The sprite emulation is incomplete and buggy. Sprite collisions and sprite
priorities in dual playfield mode are not implemented yet. The serial port
is unimplemented. Apart from that, UAE can do everything a real A500 can do
(and more), but there may still be one or two buglets that make some programs
fail (there seems to be a problem with the blitter in some demos).

13. Thanks & Acknowledgements

Thanks to all who have written me so far with bugreports and success/failure
reports when trying to run the emulator on various hardware with different
Kickstart versions. A list of everyone who has contributed to the source code
can be found in the CREDITS file (this was getting too big to keep it here).

Special thanks to:
  - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga.
  - Felix Bardos, whose HRM I "borrowed".
  - Hetz Ben Hamo mailed Peter Kittel from Commodore asking for permission to
    give Kick 1.3 away. Unfortunately, the response was negative :-(
  - Bruno Coste, Ed Hanway, Alessandro Soldo and Marko Nippula provided
    documentation

14. Ports

Apart from the "main" Unix version, several ports of UAE are ready/being
developed.

Gustavo Goedert <[e-mail]> has ported UAE to DOS using the
DJGPP port of GCC. The binary is available on several ftp sites as well as on
my Web site.

Ernesto Corvi <[e-mail]> has ported UAE to the Apple
Macintosh. He tells me it is available on Info-Mac, and that every Mac user
should know where that is. A link to the archive containing both PPC and 68k
binaries is on my Web page.

Christian Bauer <[e-mail]> has ported UAE to the
BeBox.

Ian Stephenson <[e-mail]> has ported UAE to NextStep.

Olaf 'Olsen' Barthel <[e-mail]> has ported UAE to the Amiga. This
port requires the AA chipset as well as Kickstart 3.0 or higher. CyberGraphX
is supported. Please read the file "amiga.c" for information. To compile it,
you need SAS/C and the 3.0 includes (they probably come with the compiler).

Since I generally don't have the possibility to test or improve these ports,
it is a good idea to contact their respective authors if you have questions.

15. Pointers

There are a few sites in the Internet that contain helpful information about
UAE.

I have set up a WEB page for UAE. You will find interim versions, Linux
binaries, diskfiles with Amiga software and other interesting stuff there.
The address is

http://www-users.informatik.rwth-aachen.de/~crux/uae.html

There, you will find links to other UAE pages. I'll add these links to this
document in the next version, but I don't have them here right now.

I post announcements of new versions of UAE to the newsgroup
comp.emulators.misc. From time to time, I also upload new versions to the ftp
server sunsite.unc.edu. You will find them either in pub/Linux/Incoming or in
pub/Linux/system/Emulators. There are many sunsite mirrors throughout the
world, you should be able to find one near you.

16. The author's address

Before you contact me with a problem that you have, make sure you have read
_all_ of the above. Please read also the file "FAQ", which conains a lot of
helpful information. In the future, I will probably no longer respond to
questions that are already answered by any of these files.

[e-mail]

or, via snailmail

Bernd Schmidt
Schlossweiherstrasse 14
52072 Aachen
Germany

Email is more likely to be answered, and will definitely be answered much
faster.
Please don't ask for Kickstart ROM files.